<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!--
    $Id: package.html 481833 2006-12-03 17:32:52Z niallp $

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at
   
         http://www.apache.org/licenses/LICENSE-2.0
   
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
<html>
<head>
    <title>Package Documentation for org.apache.struts.taglib.bean
        Package</title>
</head>

<body bgcolor="white">
The "struts-bean" tag library contains JSP custom tags useful in defining
new beans (in any desired scope) from a variety of possible sources, as well
as a tag to render a particular bean (or bean property) to the output
response.
<br>
<br>
<a name="doc.Description"></a>

<div align="Center"><a href="#doc.Intro">[Introduction]</a>
    <a href="#doc.Properties">[Bean Properties]</a>
    <a href="#doc.Creation">[Bean Creation]</a>
    <a href="#doc.Output">[Bean Output]</a>
</div>

<hr>  <a name="doc.Intro"></a>

<h3>Introduction</h3>

<p>Much of the power of JavaServer Pages (JSP) technology comes from the
    simple and powerful mechanisms by which the servlet that is generated
    automatically
    from your JSP source page can interact with JavaBeans that represent the
    computational
    state of your application. In standard JSP pages, the <code>&lt;jsp:useBean&gt;</code>
    tag is used create a bean (if necessary), as well as a "scripting
    variable"
    that can be used within scriptlets to refer to these beans.</p>

<p>The "struts-bean" tag library provides substantial enhancements to the
    basic capability provided by <code>&lt;jsp:useBean&gt;</code>, as
    discussed
    in the following sections:</p>

<ul>
    <li><a href="#doc.Properties">Bean Properties</a>
        - Extended syntax to refer to JavaBean properties with simple names
        (same as the standard JSP tags <code>&lt;jsp:getProperty&gt;</code>
        and
        <code>&lt;jsp:setProperty&gt;</code>), nested names (a property named
        <code>address.city</code> returns the value retrieved by the Java
        expression <code>getAddress().getCity()</code>), and indexed names (a
        property named <code>address[3]</code> retrieves the fourth address
        from
        the indexed "address" property of a bean).</li>
    <li><a href="#doc.Creation">Bean Creation</a>
        - New JSP beans, in any scope, can be created from a variety of
        objects
        and APIs associated with the current request, or with the servlet
        container
        in which this page is running.</li>
    <li><a href="#doc.Output">Bean Output</a>
        - Supports the rendering of textual output from a bean (or bean
        property),
        which will be included in the response being created by your JSP page.
    </li>

</ul>

<p>See the <a href="../../../../../../tagreference.html">Bean Tags
    Reference</a>
    for detailed information about the available tags in this tag library, and
    the valid attributes for each tag.<br>
    <img src="doc-files/beanUML.gif" alt="Bean Tag UML">
    <br>
</p>
<a name="doc.Properties"></a>

<h3>Bean Properties</h3>

<h5>Common Tag Attributes</h5>

<p>The tags in the "struts-bean" tag library (and, generally, in all tag
    libraries
    included with the Struts framework) share a common set of tag attributes
    that have the same meaning, no matter what tag they are used on. These
    common
    attributes include:</p>

<ul>
    <li><em>id</em> - Names the scripting variable that will be created
        by this custom tag, as well as the key value used to locate this bean
        in the scope defined by the <code>scope</code> attribute.</li>
    <li><em>name</em> - Defines the key value by which an existing bean will
        be looked up in the scope defined by the <code>scope</code> attribute
        (if any), or by searching through the various scopes in the standard
        order (page, request, session, application).</li>
    <li><em>property</em> - Defines the name of a JavaBeans property, of the
        JSP bean identified by the <code>name</code> and (optional) <code>
        scope</code>
        attributes, whose value is to be used by this custom tag. If not
        specified, the bean identified by <code>name</code> is itself used
        as the value of interest. See below for more discussion about how a
        property can be referenced.</li>
    <li><em>scope</em> - Identifies the JSP scope ("page", "request",
        "session",
        or "application" within which a particular bean will be searched for
        (under the key specified by the <code>name</code> attribute) or
        created
        (under the key specified by the <code>id</code> attribute). If not
        specified, beans will generally be searched for in the order listed
        above,
        or created in page scope.</li>

</ul>
<a name="doc.Properties.References"></a>

<h5>Property References</h5>

<p>Struts tags that support the <code>property</code> tag generally also
    recognize
    a rich syntax for getting and setting properties. There are three types
    of references supported: simple, nested, and indexed.</p>

<p><em>Simple References</em> - These are equivalent to the syntax you use
    with the standard <code>&lt;jsp:getProperty&gt;</code> and <code>&lt;jsp:setProperty&gt;</code>
    tags. A reference to a property named "foo" is converted into a method
    call to <code>getFoo()</code> or <code>setFoo(value)</code> (as
    appropriate),
    using the standard JavaBeans Specification naming conventions for bean
    properties.
    Struts uses the standard Java introspection APIs to identify the names of
    the actual property getter and setter methods, so your beans can provided
    customized method names through the use of a <code>BeanInfo</code> class.
    See the JavaBeans Specification, available at <a
        href="http://java.sun.com/products/javabeans/">
    http://java.sun.com/products/javabeans/</a>
    , for more information.</p>

<p><em>Nested References</em> - Nested references are used to access a
    property
    through a hierarchy of property names separated by periods ("."), similar
    to the way that nested properties are accessed in JavaScript. For example,
    the following property reference in a getter (such as the <code>&lt;bean:define&gt;</code>
    tag discussed below):</p>

<pre> property="foo.bar.baz"<br></pre>

<p>is translated into the equivalent the Java expression:</p>

<pre> getFoo().getBar().getBaz()<br></pre>

<p>If a nested reference is used in a setter (such as when an input form
    is processed), the property setter is called on the <strong>last</strong>
    property in the chain. For the above property reference, the equivalent
    Java expression would be:</p>

<pre> getFoo().getBar().setBaz(value)<br></pre>

<p><em>Indexed References</em> - Subscripts can be used to access individual
    elements of properties whose value is actually an array, or whose
    underlying
    JavaBean offers indexed getter and setter methods. For example, the
    following
    property reference in a getter (such as the <code>
    &lt;bean:define&gt;</code>
    tag discussed below):</p>

<pre> property="foo[2]"<br></pre>

<p>is translated into the equivalent of the Java expression:</p>

<pre> getFoo(2);<br></pre>

<p>while the same property reference in a setter would call the equivalent
    of:</p>

<pre> setFoo(2, value)<br></pre>

<p>As you can see from the above translations, the subscripts used in indexed
    references are <strong>zero relative</strong> (that is, the first element
    in an array is <code>foo[0]</code>), just as is true in the Java language.
</p>

<p><em>Combined References</em> - Nesting and indexing can be combined in
    arbitrary ways, so that expressions like <code>foo.bar[0].baz[2]</code>
    are
    legal. You must be careful, of course, to ensure that the actual beans
    being
    accessed by these references have properties of the appropriate names and
    types. Otherwise, JSP runtime exceptions will be thrown.</p>

<p>See the JavaDocs for <a
        href="http://jakarta.apache.org/commons/beanutils/api/org/apache/commons/beanutils/PropertyUtils.html">PropertyUtils</a>
    for more detailed information about the mechanisms that Struts uses to
    access
    properties in a general way, through Java reflection APIs.</p>

<hr>  <a name="doc.Creation"></a>

<h3>Bean Creation</h3>

<h5>Introduction</h5>

<p>New beans can be created, and introduced into one of the four standard
    JSP scopes (page, request, session, and application) through a variety of
    techniques. The following subsections describe the use of the following
    approaches:</p>

<ul>
    <li>Java Code in Action Classes</li>
    <li>Java Code in Scriptlets</li>
    <li>The Standard <code>&lt;jsp:useBean&gt;</code> Tag</li>
    <li>The Struts <code>&lt;bean:define&gt;</code> Tag</li>
    <li>Other Struts Copying Tags</li>

</ul>

<h5>Java Code in Action Classes</h5>

<p>Because the JSP pages are compiled into Servlets, your <code>Action</code>
    classes that are invoked by the Struts controller servlet have convenient
    access to three of the four standard JSP scopes (request, session, and
    application).
    It is very common practice for the business logic contained in your <code>
    Action</code> class to create results that are stored in request or
    session
    scope, which will be used by a JSP page you forward control to in
    rendering
    the next page of the user interface.</p>

<p><em>Request Scope</em> - To store a bean in request scope under name
    "cust",
    your <code>Action</code> class would execute code similar to this:</p>

<pre> Customer customer = ... create or acquire a customer reference ...;<br>
    request.setAttribute("cust", customer);<br></pre>

<p><em>Session Scope</em> - To store a bean in session scope under name "user"
    (perhaps in a logon action), your <code>Action</code> class would execute
    code similar to this:</p>

<pre> User user = ... look up valid user in the database ...;<br> HttpSession
    session = request.getSession();<br> session.setAttribute("user", user);
    <br></pre>

<p><em>Application Scope</em> - Generally, application scope beans are
    initialized
    in the <code>init()</code> method of a startup servlet. However, it is
    legal
    for an <code>Action</code> class to create such beans, if this is
    appropriate,
    like this:</p>

<pre> Foo foo = ... create a Foo ...;<br>
    servlet.getServletContext().setAttribute("foo", foo);<br></pre>

<h5>Java Code in Scriptlets</h5>

<p>While it is not a recommended practice in Struts-based applications
    (because
    developers will be tempted to mix business logic and presentation logic in
    their JSP pages), it is legal for scriptlet code in a JSP page to create
    new JavaBeans dynamically, and add them to any of the four possible
    scopes,
    as demonstrated in the code examples below:</p>

<p><em>Page Scope</em> - To store a bean in page scope under name "foo", your
    scriptlet must execute code like this:</p>

<pre>&lt;%<br> Foo foo = ... create a foo ...;<br>
    pageContext.setAttribute("foo", foo, PageContext.PAGE_SCOPE);<br>%&gt;<br>
</pre>

<p><em>Request Scope</em> - To store a bean in request scope under name
    "cust",
    your scriplet must execute code like this:</p>

<pre>&lt;%<br> Customer customer = ... create or acquire a customer reference
    ...;<br> pageContext.setAttribute("cust", customer,
    PageContext.REQUEST_SCOPE);<br>%&gt;<br></pre>

<p><em>Session Scope</em> - To store a bean in session scope under name
    "user",
    (perhaps as a result of a validated login), your scriplet must execute
    code
    like this:</p>

<pre>&lt;%<br> User user = ... look up valid user in the database ...;<br>
    pageContext.setAttribute("user", user, PageContext.SESSION_SCOPE);<br>%&gt;
    <br></pre>

<p><em>Application Scope</em> - Generally, application scope beans are
    initialized
    in the <code>init()</code> method of a startup servlet. However, a
    scriptlet
    can create such beans, if appropriate, like this:</p>

<pre>&lt;%<br> Foo foo = ... create a Foo ...;<br>
    pageContext.setAttribute("foo", foo, PageContext.APPLICATION_SCOPE);<br>%&gt;
    <br></pre>

<p><strong>NOTE</strong> - As mentioned above, using scriptlets in your JSP
    pages is strongly discouraged in a Struts based application, unless you
    are
    executing code that is <strong>only</strong> related to presentation of
    existing
    data. In general, your application's processing logic should be
    encapsulated
    in <code>Action</code> classes (or in beans or EJBs called by those
    classes),
    rather than being intermixed in your JSP pages.</p>

<h5>The Standard <code>&lt;jsp:useBean&gt;</code> Tag</h5>

<p>JavaServer Pages (JSP) offers a standard tag, <code>
    &lt;jsp:useBean&gt;</code>
    that can be used to create a new bean, or introduce a reference to an
    existing
    bean, into a JSP page. Beans (or bean references) introduced through this
    mechanism are completely interoperable with beans created by any of the
    Struts
    creation techniques described in this section.</p>

<p>You <strong>must</strong> use <code>&lt;jsp:useBean&gt;</code> to introduce
    a reference to an existing bean, if you wish to reference that bean with
    other standard JSP tags (such as <code>&lt;jsp:getProperty&gt;</code> or
    <code>
        &lt;jsp:setProperty&gt;</code>). If you only wish to reference such
    beans
    with other Struts tags, use of <code>&lt;jsp:useBean&gt;</code> is not
    required.</p>

<p>For more information about the <code>&lt;jsp:useBean&gt;</code> tag, see
    the JavaServer Pages Specification, available at <a
        href="http://java.sun.com/products/jsp/download.html">
    http://java.sun.com/products/jsp/download.html</a>
    .</p>

<h5>The Struts <code>&lt;bean:define&gt;</code> Tag</h5>

<p>Struts provides a powerful, general purpose, tag (<code>
    &lt;bean:define&gt;</code>
    ) that can be used to create a new bean, in any scope, by copying another
    bean (or the value of the property of another bean). This tag supports the
    "property" attribute, and therefore all the power of property references,
    as discused <a href="#doc.Properties.References">above</a>
    . It can be used in a variety of different ways, described further below.
    Unless you specify the "toScope" attribute, all defined beans will be
    created
    in page scope.</p>

<p><em>Introduce A String Constant</em> - You can create a new bean that
    has a constant String value (or the result of calculating a runtime
    expression):
</p>

<pre>    &lt;bean:define id="foo" value="This is a new String"/&gt;<br> &lt;bean:define
    id="bar" value='&lt;%= "Hello, " + user.getName() %&gt;'/&gt;<br> &lt;bean:define
    id="last" scope="session"<br> value='&lt;%= request.getRequestURI() %&gt;'/&gt;
    <br></pre>

<p><em>Copy An Existing Bean</em> - You can create a new reference to an
    existing
    bean object. You can specify the Java class or interface the new bean is
    expected to conform to with the "type" attribute, or accept the default
    type
    of <code>java.lang.Object</code> (this only affects the scripting variable
    that is exposed to scriptlets, so it is not generally meaningful in
    Struts-based
    applications).</p>

<pre>    &lt;bean:define id="foo" name="bar"/&gt;<br> &lt;bean:define id="baz"
    name="bop" type="com.mycompany.MyBopClass"/&gt;<br></pre>

<p><em>Copy An Existing Bean Property</em> - You can create a new bean that
    is initialized to the value returned by a property getter. The value of
    the "property" attribute can be any simple, nested, or indexed property
    reference
    that follows the rules described earlier. In the first example below, we
    also illustrate accessing the property of a request scope bean, and
    creating
    the new bean in session scope (rather than the default page scope).</p>

<pre>    &lt;bean:define id="foo" name="bar" property="baz" scope="request"
    <br> toScope="session"/&gt;<br> &lt;bean:define id="bop" name="user"
    property="role[3].name"/&gt;<br></pre>

<h5>Other Struts Copying Tags</h5>

<p>Struts offers a variety of bean creation tags that copy existing beans
    (or bean properties) from the environment within which this page is
    running,
    and the request that is currently being processed. Not all of the
    attributes
    for each tag are illustrated in the examples below - see the <a
        href="../../../../../../tagreference.html">
    Bean Tags Reference</a>
    for more information. Any bean created by these tags exists only in page
    scope, for the remainder of the current page.</p>

<p><em>Copy A Cookie</em> - You can create a new bean containing a <code>
    javax.servlet.http.Cookie</code> that was included in the current request.
    If no cookie of the specified name was included, a request time expression
    will be thrown - therefore, it is common to nest the use of this tag
    inside
    a <code>&lt;logic:present cookie="xxx"&gt;</code> tag to ensure that the
    cookie was really included. If there is the possibility that more than one
    cookie of the same name was included, specify the "multiple" attribute
    (and
    the resulting bean will be an array of Cookies, instead of a single
    Cookie).</p>

<pre>    &lt;bean:cookie id="foo" name="cookiename"/&gt;<br> &lt;bean:cookie
    id="all" name="JSESSIONID" multiple="true"/&gt;<br></pre>

<p><em>Copy A Request Header</em> - You can create a new bean containing
    the value of an HTTP header included in this request. If no header of the
    specified name was included, a request time exception will be thrown -
    therefore,
    it is common to nest the use of this tag inside a <code>&lt;logic:present
    header="xxx"&gt;</code> tag to ensure that the header was really included.
    If there is the possibility that more than one header of the same name was
    included, specify the "multiple" attribute (and the resulting value bean
    will be an array of String values, instead of a single String).</p>

<pre>    &lt;bean:header id="agent" name="User-Agent"/&gt;<br> &lt;bean:header
    id="languages" name="Accept-Language" multiple="true"/&gt;<br></pre>

<p><em>Copy A Dynamically Created Response</em> - You can generate an internal
    request to the application you are running, and turn the response data
    that
    is returned from that request into a bean (of type String). One possible
    use for this technique is to acquire dynamically created XML formatted
    data
    that will be stored in a bean and later manipulated (such as by applying
    an XSLT stylesheet). If the current request is part of a session, the
    generated
    request for the include will also include the session identifier (and thus
    be considered part of the same session).</p>

<pre>    &lt;bean:include id="text" page="/generateXml?param1=a&amp;param2=b"/&gt;
    <br></pre>

<p><em>Copy A JSP Implicitly Defined Object</em> - You can create a bean
    that is one of the JSP implicitly defined objects (see the JSP spec for
    more
    details). This is useful if you wish to perform property getter actions
    against
    the implicit object with a custom tag instead of a scriptlet.</p>

<pre>    &lt;bean:page id="app" property="application"/&gt;<br> &lt;bean:page
    id="sess" property="session"/&gt;<br></pre>

<p><em>Copy A Request Parameter</em> - You can create a new bean containing
    the value of a parameter included in this request. If no parameter of the
    specified name was included, a request time exception will be thrown -
    therefore,
    it is common to nest the use of this tag inside a <code>&lt;logic:present
    parameter="xxx"&gt;</code> tag to ensure that the parameter was really
    included.
    If there is the possibility that more than one parameter of the same name
    was included, specify the "multiple" attribute (and the resulting value
    bean
    will be an array of String values, instead of a single String).</p>

<pre>    &lt;bean:parameter id="name" name="name"/&gt;<br> &lt;bean:header
    id="options" name="option" multiple="true"/&gt;<br></pre>

<p><em>Copy a Web Application Resource</em> - You can create a new bean
    containing
    either the value of a web application resource as a String, or a <code>
    java.io.InputStream</code>
    for reading the content of that resource. The resource is accessed with
    a context-relative path (beginning with "/"), using the <code>
    ServletContext.getResource()</code>
    or <code>ServletContext.getResourceAsStream()</code> methods on the
    underlying
    application object.</p>

<pre>    &lt;bean:resource id="deployment" name="/WEB-INF/web.xml"/&gt;<br>
    &lt;bean:resource id="stream" name="/WEB-INF/web.xml"<br> input="true"/&gt;
    <br></pre>

<p><em>Copy A Struts Configuration Object</em> - You can create a new bean
    containing one of the standard Struts framework configuration objects.
    Doing
    this gives you access to the properties of the configuration object, if
    needed.
</p>

<pre>    &lt;bean:struts id="form" formBean="CustomerForm"/&gt;<br> &lt;bean:struts
    id="fwd" forward="success"/&gt;<br> &lt;bean:struts id="map"
    mapping="/saveCustomer"/&gt;<br></pre>

<hr>  <a name="doc.Output"></a>

<h3>Bean Output</h3>

<p>None of the Struts Bean tags discussed so far render any output to the
    response page that is being generated from this JSP page. They are
    executed
    in order to make relevant Java objects visible as beans for further
    manipulation.
    The following tags cause output to be written to the response, and
    therefore
    made visible to the ultimate requester.</p>

<p><em>Render An Internationalized Message</em> - You can specify a message
    key (with optional parameter replacement objects) that are passed to a <a
        href="../../util/MessageResources.html">
    MessageResources</a>
    object that returns the corresponding message text. The message text will
    be copied to the response currently being created. By default, messages
    are looked up in the application resources bundle that is initialized for
    you (as an application scope bean) by the Struts controller servlet, using
    the Locale must recently stored in the user's session. These defaults can
    be overridden by setting values for the "bundle" and "locale" attributes,
    as described in the <a
        href="../../../../../../tagreference.html#message">
    Bean Tags Reference</a>
    . </p>
<pre>    &lt;bean:message key="label.Cancel"/&gt;<br> &lt;bean:message
    key="message.hello" arg0='&lt;%= user.getFullName() %&gt;'/&gt;<br></pre>

<p><em>Render A Bean or Bean Property</em> - The contents of a bean, or bean
    property, are converted to a String and then copied to the response
    currently
    being created. This tag understands the syntax for simple, nested, and
    indexed
    property references described <a href="#doc.Properties.References">
    above</a>
    . Beans from any scope can be requested - by default, the scopes are
    searched
    in expanding visibility order (page, request, session, and application) to
    locate the requested bean.</p>

<pre>    &lt;bean:write name="username"/&gt;<br> &lt;bean:write name="user"
    property="fullName"/&gt;<br> &lt;bean:write name="customer"
    property="orders[2].partNumber"<br> scope="session"/&gt;<br></pre>

</body>
</html>
